package com.kexio.dynamic.permission.annotation;

import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;

/**
 * 动态权限注解
 * 
 * 标记在方法或类上，进行动态权限验证
 * 
 * 使用示例：
 * <pre>
 * &#64;DynamicPermission(resource = "user", action = "read")
 * public List&lt;User&gt; getUsers() {
 *     // 需要用户读取权限
 * }
 * 
 * &#64;DynamicPermission(
 *     resource = "order", 
 *     action = "update",
 *     rule = "#{order.userId == user.id}",
 *     engine = "spel"
 * )
 * public void updateOrder(Order order) {
 *     // 只能更新自己的订单
 * }
 * 
 * &#64;DynamicPermission(
 *     resource = "data", 
 *     action = "access",
 *     rule = "user.tenantId == data.tenantId",
 *     engine = "groovy"
 * )
 * public Data getData(Long dataId) {
 *     // 租户数据隔离
 * }
 * </pre>
 * 
 * @author Kexio
 * @since 1.0.0
 */
@Target({ElementType.TYPE, ElementType.METHOD})
@Retention(RetentionPolicy.RUNTIME)
public @interface DynamicPermission {

    /**
     * 资源标识
     */
    String resource();

    /**
     * 操作动作
     */
    String action() default "access";

    /**
     * 权限规则表达式
     * 支持SpEL表达式或脚本
     */
    String rule() default "";

    /**
     * 权限引擎类型
     */
    String engine() default "default";

    /**
     * 是否必需权限
     * 如果为false，权限验证失败时仅记录日志，不阻止执行
     */
    boolean required() default true;

    /**
     * 权限验证失败时的处理策略
     */
    FailureStrategy onFailure() default FailureStrategy.THROW_EXCEPTION;

    /**
     * 是否使用缓存
     */
    boolean useCache() default true;

    /**
     * 缓存过期时间（秒）
     */
    int cacheTimeout() default 300;

    /**
     * 权限组（用于批量权限验证）
     */
    String group() default "";

    /**
     * 权限条件
     * 额外的权限验证条件
     */
    String condition() default "";

    /**
     * 权限参数
     * 传递给权限引擎的参数（JSON格式）
     */
    String parameters() default "";

    /**
     * 是否记录权限验证日志
     */
    boolean logAccess() default false;

    /**
     * 权限描述
     */
    String description() default "";

    /**
     * 权限标签
     * 用于权限分类和管理
     */
    String[] tags() default {};

    /**
     * 权限级别
     */
    PermissionLevel level() default PermissionLevel.NORMAL;

    /**
     * 失败处理策略枚举
     */
    enum FailureStrategy {
        /**
         * 抛出异常
         */
        THROW_EXCEPTION,
        
        /**
         * 返回默认值
         */
        RETURN_DEFAULT,
        
        /**
         * 记录日志并继续
         */
        LOG_AND_CONTINUE,
        
        /**
         * 重定向到无权限页面
         */
        REDIRECT,
        
        /**
         * 自定义处理
         */
        CUSTOM
    }

    /**
     * 权限级别枚举
     */
    enum PermissionLevel {
        /**
         * 低级权限
         */
        LOW,
        
        /**
         * 普通权限
         */
        NORMAL,
        
        /**
         * 高级权限
         */
        HIGH,
        
        /**
         * 敏感权限
         */
        SENSITIVE,
        
        /**
         * 超级权限
         */
        SUPER
    }
}
